<HTML>
<CENTER><A HREF = "http://sparta.sandia.gov">SPARTA WWW Site</A> - <A HREF = "Manual.html">SPARTA Documentation</A> - <A HREF = "Section_commands.html#comm">SPARTA Commands</A> 
</CENTER>






<HR>

<H3>fix ave/histo command 
</H3>
<H3>fix ave/histo/kk command 
</H3>
<H3>fix ave/histo/weight command 
</H3>
<H3>fix ave/histo/weight/kk command 
</H3>
<P><B>Syntax:</B>
</P>
<PRE>fix ID style Nevery Nrepeat Nfreq lo hi Nbin value1 value2 ... keyword args ... 
</PRE>
<UL><LI>ID is documented in <A HREF = "fix.html">fix</A> command 

<LI>style = <I>ave/histo</I> or <I>ave/histo/weight</I> = style name of this fix command 

<LI>Nevery = use input values every this many timesteps 

<LI>Nrepeat = # of times to use input values for calculating histogram 

<LI>Nfreq = calculate histogram every this many timesteps 

<LI>lo,hi = lo/hi bounds within which to histogram 

<LI>Nbin = # of histogram bins 

<LI>one or more input values can be listed 

<LI>value = x, y, z, vx, vy, vz, fx, fy, fz, c_ID, c_ID[N], f_ID, f_ID[N], v_name 

<PRE>  x,y,z,vx,vy,vz = particle attribute (position, velocity component)
  c_ID = scalar or vector calculated by a compute with ID
  c_ID[I] = Ith component of vector or Ith column of array calculated by a compute with ID, I can include wildcard (see below)
  f_ID = scalar or vector calculated by a fix with ID
  f_ID[I] = Ith component of vector or Ith column of array calculated by a fix with ID, I can include wildcard (see below)
  v_name = value(s) calculated by an equal-style or particle-style or grid-style variable with name 
</PRE>
<LI>zero or more keyword/arg pairs may be appended 

<LI>keyword = <I>mode</I> or <I>file</I> or <I>region</I> or <I>mix</I> or <I>group</I> or <I>ave</I> or <I>start</I> or <I>beyond</I> or <I>overwrite</I> or <I>title1</I> or <I>title2</I> or <I>title3</I> 

<PRE>  <I>mode</I> arg = <I>scalar</I> or <I>vector</I>
    scalar = all input values are scalars
    vector = all input values are vectors
  <I>file</I> arg = filename
    filename = name of file to output histogram(s) to
  <I>region</I> arg = region-ID for particle inclusion
  <I>mix</I> arg = mixture-ID for particle inclusion
  <I>group</I> arg = group-ID for grid cell inclusion
  <I>ave</I> args = <I>one</I> or <I>running</I> or <I>window</I>
    one = output a new average value every Nfreq steps
    running = output cumulative average of all previous Nfreq steps
    window M = output average of M most recent Nfreq steps
  <I>start</I> args = Nstart
    Nstart = start averaging on this timestep
  <I>beyond</I> arg = <I>ignore</I> or <I>end</I> or <I>extra</I>
    ignore = ignore values outside histogram lo/hi bounds
    end = count values outside histogram lo/hi bounds in end bins
    extra = create 2 extra bins for value outside histogram lo/hi bounds
  <I>overwrite</I> arg = none = overwrite output file with only latest output
  <I>title1</I> arg = string
    string = text to print as 1st line of output file
  <I>title2</I> arg = string
    string = text to print as 2nd line of output file
  <I>title3</I> arg = string
    string = text to print as 3rd line of output file, only for vector mode 
</PRE>

</UL>
<P><B>Examples:</B>
</P>
<PRE>fix 1 ave/histo 100 5 1000 0.5 1.5 50 c_myGrid<B>*</B> file temp.histo ave running
fix 1 ave/histo 100 5 1000 0 5 100 c_kePart "My output values"
fix 1 ave/histo/weight 1 100 1000 -2.0 2.0 18 vx vy ave running beyond extra 
</PRE>
<P><B>Description:</B>
</P>
<P>Use one or more values as inputs every few timesteps to create a
single histogram.  The histogram can then be averaged over longer
timescales.  The resulting histogram can be used by other <A HREF = "Section_howto.html#howto_15">output
commands</A>, and can also be written to a
file.  The fix ave/histo/weight command has identical syntax to fix
ave/histo, except that exactly two values must be specified.  See
details below.
</P>
<P>A histogram is simply a count of the number of values that fall within
a histogram bin.  <I>Nbins</I> are defined, with even spacing between <I>lo</I>
and <I>hi</I>.  Values that fall outside the lo/hi bounds can be treated in
different ways; see the discussion of the <I>beyond</I> keyword below.
</P>
<P>Each input value can be a particle attribute (position, velocity), or
can be the result of a <A HREF = "compute.html">compute</A> or <A HREF = "fix.html">fix</A> that
produces global or per-particle or per-grid quantities, or the
evaluation of an equal-style or particle-style or grid-style
<A HREF = "variable.html">variable</A>.  The set of input values can be either all
global, all per-particle, or all per-grid quantities.  Inputs of
different kinds (e.g. global and per-particle) cannot be mixed.
Particle attributes are per-particle vector values.  See the doc page
for individual "compute" and "fix" commands to see what kinds of
quantities they generate.
</P>
<P>The input values must either be all scalars or all vectors (or
arrays), depending on the setting of the <I>mode</I> keyword.
</P>
<P>Note that the output of this command is a single histogram for all
input values combined together, not one histogram per input value.
See below for details on the format of the output of this fix.
</P>
<P>If <I>mode</I> = scalar, then the input values must be scalars, or vectors
with a bracketed term appended, indicating the Ith value of the vector
is used.
</P>
<P>If <I>mode</I> = vector, then the input values must be vectors, or arrays
with a bracketed term appended, indicating the Ith column of the array
is used. 
</P>
<P>Note that for values from a compute or fix, the bracketed index I can
be specified using a wildcard asterisk with the index to effectively
specify multiple values.  This takes the form "*" or "*n" or "n*" or
"m*n".  If N = the size of the vector (for <I>mode</I> = scalar) or the
number of columns in the array (for <I>mode</I> = vector), then an asterisk
with no numeric values means all indices from 1 to N.  A leading
asterisk means all indices from 1 to n (inclusive).  A trailing
asterisk means all indices from n to N (inclusive).  A middle asterisk
means all indices from m to n (inclusive).
</P>
<P>Using a wildcard is the same as if the individual elements of the
vector or columns of the array had been listed one by one.  E.g. these
2 fix ave/histo commands are equivalent, since the <A HREF = "compute_com_chunk.html">compute
grid</A> command creates a per-grid array with 3
columns:
</P>
<PRE>compute myGrid grid all all u v w
fix 1 ave/histo 100 1 100 c_myGrid file tmp1.grid mode vector
fix 2 ave/histo 100 1 100 c_myGrid[1] c_myGrid[2] c_myGrid[3] file tmp2.grid mode vector 
</PRE>
<P>If the fix ave/histo/weight command is used, exactly two values must
be specified.  If the values are vectors, they must be the same
length.  The first value (a scalar or vector) is what is histogrammed
into bins, in the same manner the fix ave/histo command operates.  The
second value (a scalar or vector) is used as a "weight".  This means
that instead of each value tallying a "1" to its bin, the
corresponding weight is tallied.  E.g. the Nth entry in the first
vector tallies the Nth entry (weight) in the second vector.
</P>
<HR>

<P>The <I>Nevery</I>, <I>Nrepeat</I>, and <I>Nfreq</I> arguments specify on what
timesteps the input values will be used in order to contribute to the
histogram.  The final histogram is generated on timesteps that are
multiple of <I>Nfreq</I>.  It is averaged over <I>Nrepeat</I> histograms,
computed in the preceding portion of the simulation every <I>Nevery</I>
timesteps.  <I>Nfreq</I> must be a multiple of <I>Nevery</I> and <I>Nevery</I> must
be non-zero even if <I>Nrepeat</I> is 1.  Also, the timesteps
contributing to the histogram value cannot overlap, 
i.e. Nrepeat*Nevery can not exceed Nfreq. 
</P>
<P>For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then input values
on timesteps 90,92,94,96,98,100 will be used to compute the final
histogram on timestep 100.  Similarly for timesteps
190,192,194,196,198,200 on timestep 200, etc.  If Nrepeat=1 and Nfreq
= 100, then no time averaging of the histogram is done; a histogram is
simply generated on timesteps 100,200,etc.
</P>
<HR>

<P>The particle attribute values (x,y,z,vx,vy,vz) are self-explanatory.
</P>
<P>If a value begins with "c_", a compute ID must follow which has been
previously defined in the input script.  If <I>mode</I> = scalar, then if
no bracketed term is appended, the global scalar calculated by the
compute is used.  If a bracketed term is appended, the Ith element of
the global vector calculated by the compute is used.  If <I>mode</I> =
vector, then if no bracketed term is appended, the global or per-atom
or local vector calculated by the compute is used.  If a bracketed
term is appended, the Ith column of the global or per-particle or
per-grid array calculated by the compute is used.  See the discussion
above for how I can be specified with a wildcard asterisk to
effectively specify multiple values.
</P>
<P>Note that there is a <A HREF = "compute_reduce.html">compute reduce</A> command
which can sum per-particle or per-grid or per-surf quantities into a
global scalar or vector which can thus be accessed by fix ave/histo.
Users can also write code for their own compute styles and <A HREF = "Section_modify.html">add them
to SPARTA</A>.
</P>
<P>If a value begins with "f_", a fix ID must follow which has been
previously defined in the input script.  If <I>mode</I> = scalar, then if
no bracketed term is appended, the global scalar calculated by the fix
is used.  If a bracketed term is appended, the Ith element of the
global vector calculated by the fix is used.  If <I>mode</I> = vector, then
if no bracketed term is appended, the global or per-atom or local
vector calculated by the fix is used.  If a bracketed term is
appended, the Ith column of the global or per-particle or per-grid
array calculated by the fix is used.  See the discussion above for how
I can be specified with a wildcard asterisk to effectively specify
multiple values.
</P>
<P>Note that some fixes only produce their values on certain timesteps,
which must be compatible with <I>Nevery</I>, else an error will result.
Users can also write code for their own fix styles and <A HREF = "Section_modify.html">add them to
SPARTA</A>.
</P>
<P>If a value begins with "v_", a variable name must follow which has
been previously defined in the input script.  If <I>mode</I> = scalar, then
only equal-style variables can be used.  If <I>mode</I> = vector, then only
particle-style or grid-style variables can be used, which produce
per-particle per-grid vectors respectively.  See the
<A HREF = "variable.html">variable</A> command for details.
</P>
<P>Note that variables of style <I>equal</I>, <I>particle</I>, and <I>grid</I> define a
formula which can reference individual particle properties or stats
output keywords, or they can invoke other computes, fixes, or
variables when they are evaluated, so this is a very general means of
specifying quantities to histogram.
</P>
<HR>

<P>Additional optional keywords also affect the operation of this fix.
</P>
<P>If the <I>mode</I> keyword is set to <I>scalar</I>, then all input values must
be global scalars, or elements of global vectors.  If the <I>mode</I>
keyword is set to <I>vector</I>, then all input values must be global or
per-particle or per-grid vectors, or columns of global or per-particle
or per-grid arrays.
</P>
<P>The <I>file</I> keyword allows a filename to be specified.  Every <I>Nfreq</I>
steps, one histogram is written to the file.  This includes a leading
line that contains the timestep, number of bins, the total count of
values contributing to the histogram, the count of values that were
not histogrammed (see the <I>beyond</I> keyword), the minimum value
encountered, and the maximum value encountered.  The min/max values
include values that were not histogrammed.  Following the leading
line, one line per bin is written into the file.  Each line contains
the bin #, the coordinate for the center of the bin (between <I>lo</I> and
<I>hi</I>), the count of values in the bin, and the normalized count.  The
normalized count is the bin count divided by the total count (not
including values not histogrammed), so that the normalized values sum
to 1.0 across all bins.
</P>
<P>The <I>region</I>, <I>mix</I>, and <I>group</I> keywords limit which particles
or grid cells are included in the histogramming.
</P>
<P>The <I>region</I> keyword only applies to per-particle histogramming.  Only
particles in the specified <I>region-ID</I> are included in the histogram.
See the <A HREF = "region.html">region</A> command for details of how geometric
regions are defined.
</P>
<P>The <I>mix</I> keyword only applies to per-particle histogramming.  Only
particles whose species are in the specified <I>mixture-ID</I> are included
in the histogram, which allows for only a subset of species to be
included.  See the <A HREF = "mixture.html">mixture</A> command for details of how
mixtures are defined.
</P>
<P>The <I>group</I> keyword only applies to per-grid cell histogramming.  Only
grid cells in the grid group specified by <I>group-ID</I> are included in
the histogram.  See the <A HREF = "group.html">grid group</A> command for details of
how grid groups are defined.
</P>
<P>The <I>ave</I> keyword determines how the histogram produced every <I>Nfreq</I>
steps are averaged with histograms produced on previous steps that
were multiples of <I>Nfreq</I>, before they are accessed by another output
command or written to a file.
</P>
<P>If the <I>ave</I> setting is <I>one</I>, then the histograms produced on
timesteps that are multiples of <I>Nfreq</I> are independent of each other;
they are output as-is without further averaging.
</P>
<P>If the <I>ave</I> setting is <I>running</I>, then the histograms produced on
timesteps that are multiples of <I>Nfreq</I> are summed and averaged in a
cumulative sense before being output.  Each bin value in the histogram
is thus the average of the bin value produced on that timestep with
all preceding values for the same bin.  This running average begins
when the fix is defined; it can only be restarted by deleting the fix
via the <A HREF = "unfix.html">unfix</A> command, or by re-defining the fix by
re-specifying it.
</P>
<P>If the <I>ave</I> setting is <I>window</I>, then the histograms produced on
timesteps that are multiples of <I>Nfreq</I> are summed within a moving
"window" of time, so that the last M histograms are used to produce
the output.  E.g. if M = 3 and Nfreq = 1000, then the output on step
10000 will be the combined histogram of the individual histograms on
steps 8000,9000,10000.  Outputs on early steps will be sums over less
than M histograms if they are not available.
</P>
<P>The <I>start</I> keyword specifies what timestep histogramming will begin
on.  The default is step 0.  Often input values can be 0.0 at time 0,
so setting <I>start</I> to a larger value can avoid including a 0.0 in
a running or windowed histogram.
</P>
<P>The <I>beyond</I> keyword determines how input values that fall outside the
<I>lo</I> to <I>hi</I> bounds are treated.  Values such that <I>lo</I> <= value <=
<I>hi</I> are assigned to one bin.  Values on a bin boundary are assigned
to the lower of the 2 bins.  If <I>beyond</I> is set to <I>ignore</I> then
values < <I>lo</I> and values > <I>hi</I> are ignored, i.e. they are not binned.
If <I>beyond</I> is set to <I>end</I> then values < <I>lo</I> are counted in the
first bin and values > <I>hi</I> are counted in the last bin.  If <I>beyond</I>
is set to <I>extend</I> then two extra bins are created, so that there are
Nbins+2 total bins.  Values < <I>lo</I> are counted in the first bin and
values > <I>hi</I> are counted in the last bin (Nbins+1).  Values between
<I>lo</I> and <I>hi</I> (inclusive) are counted in bins 2 thru Nbins+1.  The
"coordinate" stored and printed for these two extra bins is <I>lo</I> and
<I>hi</I>.
</P>
<P>The <I>overwrite</I> keyword will continuously overwrite the output file
with the latest output, so that it only contains one timestep worth of
output.  This option can only be used with the <I>ave running</I> setting.
</P>
<P>The <I>title1</I> and <I>title2</I> and <I>title3</I> keywords allow specification of
the strings that will be printed as the first 3 lines of the output
file, assuming the <I>file</I> keyword was used.  SPARTA uses default
values for each of these, so they do not need to be specified.
</P>
<P>By default, these header lines are as follows:
</P>
<PRE># Histogram for fix ID
# TimeStep Number-of-bins Total-counts Missing-counts Min-value Max-value
# Bin Coord Count Count/Total 
</PRE>
<P>In the first line, ID is replaced with the fix-ID.  The second line
describes the six values that are printed at the first of each section
of output.  The third describes the 4 values printed for each bin in
the histogram.
</P>
<HR>

<P><B>Restart, output info:</B>
</P>
<P>No information about this fix is written to <A HREF = "restart.html">binary restart
files</A>.
</P>
<P>This fix produces a global vector and global array which can be
accessed by various output commands.  The values can only be accessed
on timesteps that are multiples of <I>Nfreq</I> since that is when a
histogram is generated.  The global vector has 4 values:
</P>
<UL><LI>1 = total counts in the histogram
<LI>2 = values that were not histogrammed (see <I>beyond</I> keyword)
<LI>3 = min value of all input values, including ones not histogrammed
<LI>4 = max value of all input values, including ones not histogrammed 
</UL>
<P>The global array has # of rows = Nbins and # of columns = 3.  The
first column has the bin coordinate, the 2nd column has the count of
values in that histogram bin, and the 3rd column has the bin count
divided by the total count (not including missing counts), so that the
values in the 3rd column sum to 1.0.
</P>
<HR>

<P>Styles with a <I>kk</I> suffix are functionally the same as the
corresponding style without the suffix.  They have been optimized to
run faster, depending on your available hardware, as discussed in the
<A HREF = "Section_accelerate.html">Accelerating SPARTA</A> section of the manual.
The accelerated styles take the same arguments and should produce the
same results, except for different random number, round-off and
precision issues.
</P>
<P>These accelerated styles are part of the KOKKOS package. They are only
enabled if SPARTA was built with that package.  See the <A HREF = "Section_start.html#start_3">Making
SPARTA</A> section for more info.
</P>
<P>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <A HREF = "Section_start.html#start_6">-suffix command-line
switch</A> when you invoke SPARTA, or you can
use the <A HREF = "suffix.html">suffix</A> command in your input script.
</P>
<P>See the <A HREF = "Section_accelerate.html">Accelerating SPARTA</A> section of the
manual for more instructions on how to use the accelerated styles
effectively.
</P>
<HR>

<P><B>Restrictions:</B> none
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "compute.html">compute</A>, <A HREF = "fix_ave_time.html">fix ave/time</A>,
<A HREF = "variable.html">variable</A>
</P>
<P><B>Default:</B> none
</P>
<P>The option defaults are mode = scalar, ave = one, start = 0, no file
output, no region/mixture/group restriction on inclusion of particles
or grid cells, beyond = ignore, and title 1,2,3 = strings as described
above.
</P>
</HTML>
